---
title: Astro 사이트를 Github Pages에 배포하세요
description: Github Pages를 사용하여 Astro 사이트를 웹에 배포하는 방법.
type: deploy
i18nReady: true
---

[Github Pages](https://pages.github.com/)를 사용하여 [GitHub.com](https://github.com/) 저장소에서 직접 Astro 웹사이트를 호스팅할 수 있습니다.

## 배포 방법

[GitHub Actions](https://github.com/features/actions)를 사용하면 Astro 사이트를 Github Pages에 배포하여 사이트를 자동으로 빌드하고 배포할 수 있습니다. 이렇게 하려면 소스 코드가 GitHub에서 호스팅되어야 합니다.

Astro는 아주 작은 구성으로 프로젝트를 배포하기 위해 공식 `withastro/action`을 유지 관리합니다. 아래 지침에 따라 Astro 사이트를 Github Pages에 배포하고, 추가 정보가 필요한 경우 [패키지 README](https://github.com/withastro/action)를 참조하세요.

## Github Pages용 Astro 구성

### `github.io` URL에 배포

`astro.config.mjs`에서 [`site`](/ko/reference/configuration-reference/#site) 및 [`base`](/ko/reference/configuration-reference/#base) 옵션을 설정하세요.
    
```js title="astro.config.mjs" ins={4-5}
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: 'my-repo',
})
```

#### `site`

`site` 값은 다음 중 하나여야 합니다.

- 사용자 이름에 기반한 URL: `https://<username>.github.io`
- [GitHub Organization의 비공개 페이지](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site)에 대해 자동 생성된 임의의 URL: `https://<random-string>.pages.github.io/`

#### `base`

Astro가 저장소 이름 (예: `/my-repo`)을 웹 사이트의 루트로 처리하려면 `base` 값이 필요할 수 있습니다.

:::note
  다음과 같은 경우 `base` 매개변수를 설정하지 마세요.

- 페이지가 루트 폴더에서 제공되는 경우
- 저장소가 `https://github.com/<USERNAME>/<USERNAME>.github.io`에 위치한 경우
:::

`base` 값은 슬래시로 시작하는 저장소 이름이어야 합니다 (예: `/my-blog`). 이는 Astro가 여러분의 웹사이트 루트가 기본 `/`가 아닌 `/my-repo`임을 이해하기 위한 것입니다.

:::caution
    이 값이 구성되면 모든 내부 페이지 링크 앞에 `base` 값이 붙어야 합니다.

```astro ins="/my-repo"
<a href="/my-repo/about">About</a>
```

[`base` 값 구성](/ko/reference/configuration-reference/#base)에 대해 자세히 알아보세요.
:::

### 사용자 정의 도메인으로 Github Pages 사용

:::tip[Set up a custom domain]
프로젝트에 다음 `./public/CNAME` 파일을 추가하여 사용자 정의 도메인을 설정할 수 있습니다.

```js title="public/CNAME"
sub.mydomain.com
```

`user.github.io` 대신 사용자 정의 도메인에 사이트가 배포됩니다. [도메인 공급자에 대한 DNS도 구성](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)하는 것을 잊지 마세요. 
:::

사용자 정의 도메인과 함께 Github Pages를 사용하도록 Astro를 구성하려면 도메인을 `site` 값으로 설정하세요. `base` 값을 설정하지 마세요:

```js title="astro.config.mjs" ins={4}
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://example.com',
})
```

## GitHub Action 구성

1. 프로젝트의 `.github/workflows/deploy.yml`에 새 파일을 만들고 아래 YAML에 붙여넣습니다.

    ```yaml title="deploy.yml"
    name: Deploy to GitHub Pages

    on:
      # 'main' 브랜치로 푸시할 때마다 워크플로를 트리거합니다.
      # 다른 브랜치 이름을 사용하시나요? `main`을 브랜치 이름으로 바꾸세요.
      push:
        branches: [ main ]
      # GitHub의 Actions 탭에서 이 워크플로를 수동으로 실행할 수 있습니다.
      workflow_dispatch:
      
    # Allow this job to clone the repo and create a page deployment
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v4
          - name: Install, build, and upload your site
            uses: withastro/action@v2
            # with:
              # path: . # 저장소 내 Astro 프로젝트의 루트 위치입니다. (선택 사항)
              # node-version: 20 # 사이트를 빌드하는 데 사용해야 하는 특정 버전의 Node입니다. 기본값은 20입니다. (선택 사항)
              # package-manager: pnpm@latest # 종속성을 설치하고 사이트를 빌드하는 데 사용해야 하는 노드 패키지 관리자입니다. lockfile을 기반으로 자동으로 감지됩니다. (선택 사항)

      deploy:
        needs: build
        runs-on: ubuntu-latest
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
    ```

    :::note
    astro action에는 몇 가지 선택적 입력이 필요합니다. 이는 `with:` 줄과 사용하려는 입력의 주석을 제거하여 제공할 수 있습니다.
    :::
    
    :::caution
    공식 Astro [action](https://github.com/withastro/action)은 lockfile을 검색하여 선호하는 패키지 관리자(`npm`, `yarn`, `pnpm`, `bun`)를 감지합니다. 패키지 관리자가 자동으로 생성한 `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb` 파일을 저장소에 커밋해야 합니다.
    :::

2. GitHub에서 저장소의 **Settings** 탭으로 이동하여 설정의 **Pages** 섹션을 찾습니다.

3. 사이트의 **Source**로 **GitHub Actions**를 선택합니다.

4. 새 워크플로 파일을 커밋하고 GitHub에 푸시합니다.

이제 여러분의 사이트가 게시됩니다! Astro 프로젝트 저장소에 변경 사항을 푸시하면 GitHub Action이 자동으로 배포합니다.
